QUICKDRAW™ 3D Renderer Virtual Accelerator(RAVE) DDK 1.0.5
APPLE COMPUTER 3/30/96
WHAT IS "QUICKDRAW 3D RAVE"?
QuickDraw 3D RAVE is a low-level abstraction layer for 3D hardware accelerators. Because RAVE is an abstraction layer, it provides a common layer which can be used to access a variety of different hardware accelerators. RAVE also provides a default software rasterizer which is always available, even on systems that don't have a hardware accelerator installed.
The QuickDraw 3D Interactive Renderer uses RAVE to do all interactive rendering. As a result, QuickDraw 3D automatically works with any hardware accelerator which has a RAVE plug-in.
ABOUT THIS RELEASE
This is the GM release of RAVE 1.05. There are currently no known bugs in the QD3D RAVE Manager or the Software Engine. However, if you find problems please report bugs to
Brent Pease
APPLELINK: PEASE
email: brent@apple.com
RAVE DISTRIBUTION
RAVE is being distributed in the form of a DDK (Device Driver Kit) and a SDK(Software Developers Kit). The DDK is primarily for hardware vendors who are developing 3D accelerators to run with QuickDraw 3D and any other application that uses RAVE. The SDK is primarily for game developers who need direct access to low level 3D rasterization functions such as texture mapping and z-buffered drawing.
WHAT'S IN THIS DDK?
This DDK contains the 1.0.5 release of QuickDraw 3D RAVE. This release matches the hardware acceleration interface of the QuickDraw 3D 1.0 release, so any RAVE engine developed with this DDK will work with QD3D 1.0 (or later) based applications. Additionally, there are new APIs in this release that will be used by QD3D 1.1 to achieve much improved immediate mode rendering performance, see the What's New section for more information.
The contents of this DDK/SDK were all developed using the Metrowerks™ development environment, from the CW8 CD. We recommend an on-line reference for Macintosh programming (e.g. the ThinkC™ Reference or QuickView™) as well, particularly if you're not an experienced Macintosh programmer.
WHAT'S NEW IN 1.05
This release contains two new APIs, the TriMesh and support for color lookup tables. These APIs are documented in the ERS(Engineering Requirements Document) that has been distributed with this release. Final documentation for RAVE will be available soon.
The new manager will decompose TriMeshes into triangles so that existing engines will still be 100% compatible with new QD3D releases. However, the managers does not provide any support for color lookup tables. This means that the engine must support it or the API calls for color lookup tables will return the error kQANotSupported.
The name of the plug-in has changed from QuickDraw 3D Acceleration Layer to QuickDraw 3D RAVE. For the curious RAVE stands for Renderer Accelerator Virtual Engine.
TESTLINKED/TESTSHARED
TestLinked and TestShared are two versions of the RAVE_Test application. The only difference between these versions is that TestLinked directly links in the empty drawing engine (described below), while TestShared loads the engine through the RAVE plug-in mechanism. You can use whichever version of RAVE_Test you like; usually it's easier to begin using the TestLinked version, and move to the TestShared version later. Note that you use the "SharedEmpty.µ" project to build your drawing engine as a shared library before you can use TestShared; see "USING SHARED LIBRARIES" below for more discussion. Note that TestLinked will produce a warning message about ignoring a duplicate engine, please ignore it. Tthe reason for this is that the engine is linked in with the application and is present as a shared library.
RAVE_Test opens two windows, using a different drawing engine for each window, and runs a series of simple RAVE rendering tests to both windows. RAVE_Test is primarily for vendors developing their own drawing engine, as it provides a convenient way to compare your results with those from the Apple Software drawing engine. However, this application also provides sample application code for how to use RAVE for drawing.
RAVE_Test runs tests that draw points, lines, Gouraud triangles and texture triangles. Each test is run four ways: Single buffered, double buffered, single buffered with 2D clipping, and double buffered with 2D clipping.
EMPTY ENGINE
RAVE_Test includes "Empty Engine", a sample RAVE drawing engine with empty stubs for the drawing functions. This provides a convenient place to begin implementing a drawing engine. The TestLinked.µ project file links "Empty Engine" directly with the RAVE_Test application, so when you run it the second window is assigned to "Empty Engine". Nothing appears there, of course, as "Empty Engine" doesn't do anything. But that proves that it has actually been registered with the RAVE manager! See "USING SHARED LIBRARIES", below, for how to build "Empty Engine" as a shared library instead of linking it directly.
SNEAK3VIEW
Sneak3View is a much more powerful test and verification application. It's build with Metrowerks PowerPlant. We've included source, so you can either just use the application, or you can build it yourself and add additional tests. Please look in the Sneak3View folder for more information.
QUICKDRAW™ 3D RAVE
"QuickDraw™ 3D RAVE" is a shared library that contains the RAVE manager and Apple's software rasterizer. You need to link with it whenever you are making RAVE calls. Two versions are included, in two folders called "QD3D RAVE (debug on)" and "QD3D RAVE (debug off)". The debug on version does extensive parameter and semantic checking of all RAVE calls; this is particularly useful when you are developing application code that drives RAVE. The debug off version is the optimized release shipped with QuickDraw 3D 1.0, and performs no (or minimal) validation checking.
If you are developing a drawing engine, and you're confident that the application code is correct, you may find it more convenient to develop with the "QuickDraw™ 3D RAVE" library that has debug turned off. This is because the debug on version actually inserts it's own functions and data types between the application calls (e.g. QADrawPoint()) and the drawing engine. If you use the debug off library, calls like this pass directly to your engine's code, which may be more convenient for debugging.
APPLE SOFTWARE RASTERIZER
This release includes "QuickDraw™ 3D RAVE" version 1.0.5, which includes a software plug-in which implements a complete (although basic) RAVE feature set. Some notes on the software rasterizer features:
— Rendering to any GDevice, and to 16 or 32 bit memory devices is supported. Rendering is optimized for 16 and 32 bit deep GDevices; all others are supported by rendering 16 bits offscreen and then blitting.
— Texture mapping is point-sampled from the closest mipmap level.
HEADERS
This folder holds the RAVE.h and RAVE_system.h header files, as described by the RAVE ERS. RAVE.h should be included by application code that uses RAVE. RAVE_system.h is only required by drawing engine code. Note that Drive3D.h and Drive3D_system.h have been included for backwards compatibility and they simply #include their corresponding new filename.
USING SHARED LIBRARIES
Your preferred "QuickDraw™ 3D RAVE" library (i.e. with or without debugging) needs to be either in your application's folder (usually the most convenient for development) or in the System Extensions folder. The same is true of your drawing engine shared library (if present). In this DDK we've placed a copy of the debug-on "QuickDraw™ 3D RAVE" library in the application folder, so right now the RAVE_Test application is being run with debug on.
Once your drawing engine is stable, you may prefer to build it as a RAVE shared library. The "SharedEmpty.µ" project demonstrates how to do this. In general it's pretty easy: Just build a shared library with creator 'tnsl', and call QARegisterEngine() from your init function. WARNING: Once you have built your engine this way, you should switch to using the TestShared application, as it will confuse the RAVE manager to have your drawing engine both linked in and as a shared library!
As an experiment, try running the TestShared application _without_ the EmptyEngine plug-in in the application folder. The second window will be named "<No Drawing Engine>", indicating that the application wasn't able to find a second drawing engine to load. If you move EmptyEngine back into the application folder, the window will be titled "Empty Drawing Engine", indicating that the plug-in is being loaded.
Another experiment is to run TestLinked _with_ EmptyEngine in the folder. If you use the debug library, this will cause a warning message indicating that a duplicate drawing engine is being ignored. This is because the engine was registered twice, once from the linked version, and once via the plug-in mechanism. Therefore, if you're using TestLinked, you should not have a shared library version of the engine present as well.
